SAML Authentication

Security Assertion Markup Language (SAML) is an open standard that enables the exchange of security credentials between an identity provider and a service provider. This enables single sign-on, allowing the use of one set of credentials (for each user) to login to many different websites and web services. SAML is generally used to increase security and enhance user experience.

SAML can be used as the authentication provider in Pyramid. Start by selecting SAML as the authentication provider in the Admin console under security, and then define the SAML Settings and Initial User.

There are different SAML settings required by each SAML vendor supported by Pyramid. The generic SAML setup is also available for other non-suported vendors.

  • Click here to see a list of supported authentication providers for SAML, their capabilities and links to their specific setups.

Note: This feature is available with Enterprise licensing only.

Important: If Same Site client security is set to Strict when using SAML authentication, this may cause a loop redirect between Pyramid and the SAML provider, as cookies are prevented from working across different web domains.

SAML Authentication Flow for Users

Each user must login once to the single sign-on with the identity provider. When the user tries to access the service provider, it sends an authorization and authentication request to the identity provider. The identity provider checks the user's credentials and determines whether the user is authorized to access the required service. If the user is authorized, it sends a SAML assertion (an XML document) from the service provider, with the authorization and authentication messages.

General SAML Setup

Whether you have just installed Pyramid or you are migrating from one Authentication Provider to another, you will need to Change Provider. After which, you will need to convert your existing users to the new SAML provider.

Provider Settings

The following fields are required for most vendors.

  • Remove Auth Context Enforcement
  • Enable Windows authentication: (ADFS only.) Select this checkbox to indicate that Windows Authentication is enabled for Active Directory.
  • Consumer URL: This will be the Pyramid web site address that will be "called" back by the SAML provider. Typically this should be "https://myPyramidSite.com."
  • SAML Issuer: The access token or identifier provided from the SAML provider to confirm the incoming application is Pyramid.
  • IDP URL: The SAML provider's URL address - effectively the destination where the SAML request must be sent.
  • Logout URL: The URL that the user is redirected to after successfully signing out of Pyramid.

Certificate

The (Base64) certificate is a signed certificate provided by the SAML provider to allow Pyramid to decrypt the assertion messages coming in from the IDP. The certificate is provided by the SAML provider itself. This is CRITICAL.

Signature Settings

If your SAML Vendor is Ping (formerly ForgeRock) you can sign your outgoing requests. To do so, you need to enable the functionality and supply details of an active signing certificate and private key:

  • Sign outgoing requests: Enable and disable outgoing request signing.
  • Supply details of the signing key and certificate pair:
    • Signing Certificate: Paste the signing certificate for Ping. This is a Base64 certificate in the PEM format
    • Signing Private Key: Paste the private key for Ping. This is an RSA Key with a length of 2048-bits.

User Provisioning Settings

You can provide User Provisioning Settings for some SAML providers. These details are used by Pyramid to query the Authentication Provider and are required to enable add user through search and group roles in provisioning.

Initial User

An initial user is required for all SAML setups. This is the initial master user (from the SAML framework) that will be matched in Pyramid.

  • User Name: The internal user name of the initial user. This is a bypass for the user when working outside of SAML.
  • Password: The internal password for the user. Only used if manually logging in without the SAML framework.
  • First Name: The first name of the initial user.
  • Last Name: The last name of the initial user.
  • Email: The email of the initial user.
  • External ID: The SAML login ID of the initial user. This is typically in the format someone@domain.com and is the critical element that will enable Pyramid to match the incoming SAML assertion with the user account.

Tip: To login manually, you can use the /login/login.html or just /login entrypoints.

Get your External ID

  1. Click Test.

    2. A token is generated to use as your external ID.

  2. Copy the value and paste it into the External ID field in Pyramid.